15. Distance Matrix and Directions Specifics

Distance Matrix and Directions Specifics

Distance Matrix API requests are made with a combination of ORIGIN and DESTINATION values, as well as a TRAVELMODE. Here are some watchpoints when making requests:

  • Regardless of the travel mode chosen, you can pass in up to 25 origin or 25 destinations per request, but ONLY up to 100 elements and elements = origins*destinations. For example, 10 origins and 10 destinations = 100 elements. This value is increased to up to 625 elements for Premium Plan customers, when using the Web Service.
  • While most other services are Rate Limited (queries per second can’t exceed 50), the Distance Matrix API is rate limited in terms of ELEMENTS (not queries). If too many elements are requested within a certain time period, an OVER_QUERY_LIMIT response code will be returned.
  • Some parameters only are valid for certain travel modes - for example:
    • AvoidTolls and AvoidHighways are ignored if the travel mode = transit
    • All of the TransitOptions are only valid if the travel mode = transit
    • departureTime can be passed as part of the DrivingOptions or TransitOptions parameters


Directions API requests also involve ORIGIN, DESTINATION and TRAVELMODE but have the optional parameters of WAYPOINTS or VIA points as well. Here are some watchpoints when making requests:

  • For the client-side Directions service (using the Javascript API), up to 8 waypoints per request can be specified, in addition to the origin and destination, making a total of 10 geocoded points per request. This limit increases from 8 to 23 for Premium Plan customers
  • For the web service, up to 23 waypoints per request can be specified as long as you provide a valid identifier, such as your API key. Your response code will indicate if this is exceeded.
  • Waypoints are not supported for the TRANSIT travel mode

Next Concept